Inside Macintosh: Overview /

Preface - Going Further

Maintaining Compatibility

Compatibility is the ability of an application to execute properly in different operating environments. Compatibility is important if you want to write software that runs, with little or no modification, on all members of the Macintosh family and in all system software versions.

The key to achieving compatibility is not to depend on things that may change. Inside Macintosh contains numerous warnings about which information is likely to change. As the Operating System and Toolbox evolve to accommodate the needs of developers and users, many of their elements will vary. Whenever possible, Apple Computer strives to add features without altering existing programming interfaces. In general, you can assume that Operating System and Toolbox routines are less likely to change than data structures. Therefore, you should never directly manipulate data structures that are internal to a manager or system software routine, even if their structure is documented. Instead, you should manipulate those structures only indirectly, by calling Operating System and Toolbox routines that achieve the desired effect. In particular, you should never alter any portion of a data structure marked as unused or reserved.

Another key to writing compatible code is to code defensively. Do not assume that users perform actions in a particular order, and do not assume that function and procedure calls always succeed. You should always test the return values of routines for errors, as illustrated in most of the code samples presented in this book.

Here are some more specific guidelines to keep in mind as you write your application:

• Never address hardware directly; whenever possible, use the routines provided by the various device drivers and managers to send data to the available hardware. The addresses of memory-mapped hardware are always subject to change, as is the hardware itself. More important, direct access to such hardware is not possible in every operating environment. In multi-user systems like A/UX, for instance, the operating system manipulates all hardware; applications simply cannot write directly to hardware addresses.
• Avoid writing directly to the screen. Use QuickDraw routines whenever possible to draw on the screen. If you absolutely must write directly to the screen, do not assume that the screen is a fixed size or that it is in a fixed location. The location, size, and bit depth of the screen differ in various machines.
• Don't rely on system global variables. Many of these variables are documented in Inside Macintosh, but many are not. In particular, you must avoid undocumented system global variables because they are most likely to change. But you should try to avoid even well-known system global variables because they may not be available in all environments or in the future. In general, you can avoid using system global variables by using available routines that return the same information. (For example, the TickCount function returns the same value that is contained in the system global variable Ticks.)